COMMENT ⊗   VALID 00006 PAGES
C REC  PAGE   DESCRIPTION
C00001 00001
C00002 00002	Guide to vision routines on [VIS,HPM]
C00012 00003	VIXHDR.SAI   for displaying grey scale and halftone pictures on data disc.
C00016 00004	FNTHDR.SAI   for inserting XGP font characters into pictures.
C00019 00005	INTERNAL PICTURE ARRAY FORMAT
C00021 00006	PICTURE FILE FORMAT
C00023 ENDMK
C⊗;
Guide to vision routines on [VIS,HPM]

PIXHDR.SAI   utility routines for getting, saving, moving, etc. pictures

	requires: PIXFAI.REL,PIXSAI.REL

	provides:
		  PCLN,PCWD,PCBY,PCBYA,LNWD,LNBY,	where to find things in
		  LNBYA,WDBY,WDBI,BYBI,BPTAB,LINTAB	picture arrays


	VALUE  ←  PIXEL(PICTURE,ROW,COLUMN);		value of a particular pixel
        VALUE  ←  INTREL(PIC,ROW,COL);  interpolating PIXEL. ROW, COL, VALUE real.
		  PUTEL(PICTURE,ROW,COLUMN,VALUE);	change a pixel
		  ADDEL(PICTURE,ROW,COLUMN,VALUE);	increment a pixel
		  ADDIEL(PIC,ROW,COL,VAL); interpolating ADDEL. R, C, V real.

        SIZE   ←  PFLDIM(FILNAME);		size of array needed for pic file
	SIZE   ←  GETPFD(FILNAME,DIM[0:10]);    read in parameters of picture
        SIZE   ←  GETPFL(FILNAME,PICTURE);		read in a pic file
		  PUTPFL(PICTURE,FILENAME,MODE(1)); write PICTURE into a file
			if MODE=2, file is data compressed, otherwise normal

	CHAN   ←  OPNPFL(FILNAME,DIM[0:10]);    read in parameters of picture,
                        opened for input at 1st scanline
	CHAN   ←  CREPFL(DIM[0:10],FILENAME,MODE(1));  write header for PIC file,
                    opened for output at 1st scanline. data compressed if MODE=2 
		  PFLIN(CHAN,AR[1],NWDS); read next NWDS words from pic into AR
		  PFLOUT(CHAN,AR[1],NWDS); write next NWDS words to pic from AR
		  PFLCLS(CHAN); close picture open on channel
                   (the previous three routines (as opposed to ARRYIN,
                    ARRYOUT and RELEASE) MUST be used if data compressed
		    pictures are ever encountered)

        SIZE   ←  PIXDIM(HEIGHT,WIDTH,BITS);	size of array for HxWxB picture
        SIZE   ←  MAKPIX(HEIGHT,WIDTH,BITS,PICTURE); make skeleton HxWxB picture
        SIZE   ←  MAKDIM(H,W,B,P[0:10]); make 11 wd skeleton, for out of core pix
                  WIPE(PICTURE,VALU(0)); make every data word (not byte!) =VALU

                  pixtrn(src,tr,dest); transforms src into dst by array tr.
                     tr is a 3x3 real array. For all pixels (y,x) in dest
                     set (ty,tx,foo) ← (y,x,1) * transform. if (ty,tx) is
                     in src then dest(y,x) ← src(ty,tx);

		  COPPIC(PICTURE1,PICTURE2);  copy pic1 to pic2
                  TILE(PIC1,YL1,XL1, TY,TX, PIC2,YL2,XL2); take piece of size
			TYxTX at YL1,XL1 in PIC1, deposit at YL2,XL2 in PIC2
                  SQTILE(PIC1,YL1,XL1, TY,TX,YSQ,XSQ, PIC2,YL2,XL2);
			a TY*YSQ by TX*XSQ tile from PIC1 with upleft at YL1,XL1
			is squished into a TY by TX tile in PIC2, YL2,XL2 upleft
			The YSQ by XSQ areas in PIC1 are summed and scaled as needed
                  SATILE(PIC1,YL1,XL1, TY,TX,YSQ,XSQ, PIC2,YL2,XL2);
                        like SQTILE, but 0 samples in PIC1 leave PIC2 unchanged
		  HAFPIC(PICTURE1,PICTURE2,MAXBIT);  reduce pic to half resolution
		  SHRINK(PICT1,PICT2);        squeeze or expand PICT1 into PICT2
			pixels are sampled, not interpolated or averaged.

                  PICADD(PICTURE,PICSUM);     add a picture to a picture
 		  PICSUB(PICA,PICDIFF);	      subtract. PICA-PICDIFF → PICDIFF
                  PICMUL(PICTURE,PICPRD);     multiply pictures. no bounds check.
		  PICSH(PIC1,PIC2,DIV);       every pixel in PIC1/DIV→PIC2

		  GRAY(PIC);	Convert to gray code.
		  UNGRAY(PIC);	Convert back.

        NRETRY ←  CAMPIX(CAMERA,YEDGE,XEDGE,PICTURE,
                    SUMS(1),BCLIP(7),TCLIP(0),MAXTRY(20)); read from a camera
        NRETRY ←  CLPADJ(CAM,BLCIP,TCLIP); find optimum clip levels for CAM
        NRETRY ←  TVSNAP(CAM,YEDG,XEDG,PIC,BCLIP,TCLIP,NTRY); primitive camera
        NRETRY ←  TVRAW(CAM,YEDG,XEDG,PIC,BCLIP,TCLIP,NTRY); routines, used by
                  TVBTMX(PIC4,PICN,XFRM,INHIBEQ);		     CAMPIX
                  TVBTMY(PIC4,PICN,XFRM,INHIBLE);
                  TVBTMZ(PIC4,PICN,XFRM,INHIBGE);

       SUM     ←  INTOP(PIC,WINSIZE,ANSARRY,YEDGE(0),XEDGE(0));interest operator
                  INTLOM(HIG,WID,ANSARRY); intop local max operator
       SIZE    ←  INTERESTDIM(PICTURE,WINDOWSIZE);  pic size needed for intrst op
		  INTEREST(PICTURE,WINDOW,RESULTPICTURE); make interest op picture

       BESTVAL ←  MATCH(PICTURE1,SY1,SX1,SY2,SX2, PICTURE2,DY1,DX1,DY2,DX2);
       BSTCOEF ←  NORCOR(PICTURE1,SY1,SX1,SY2,SX2, PICTURE2,DY1,DX1,DY2,DX2);
                   ;correlators, find Source window in pic1 in Dest in pic2

		  CLEAN(PICTURE);	remove single pixel noise, blurs a little
		  PASSHI(PICTURE1,WINDOWSIZE,PICTURE2);   high pass filter
		  LOWPAS(PICTURE);     in place low pass filter. 4 pxls → 1 pxl.
        SUM    ←  CMPPAR(PICTURE1,PICTURE2);  compare two pics [ sig(x-y)↑2 ]
        SUM    ←  CMPPAD(PICTURE1,PICTURE2);  quick and dirty compare

		  PERBIT(PICTURE, TRANSFORM); transform each pixel of pic
		  HISTOG(PICTURE, HISTOGRAM); count # of occurences of each gray val
		  ENHANCE(PICTURE);	      make histogram flat
		  SYNCHRONIZE(PICTURE1);      do a vertical roll fixup

		  ROWSUM(PICTURE1,ROWSUMS);   sum up the pixels in each row
		  ROWSUD(PICTURE1,ROWSUMS);   dirty rowsums, one pixel/word used
		  COLSUM(PICTURE1,COLSUMS);   sum up the pixels in each col
       LONG REAL← SUMSQR(PIC);		      double prec. sum of squares of pixels
	MASS	← CENTRO(PIC,YL,XL,YH,XH,THR); centroid and moment of a dark area

                  UNPACK(SOURCEARRAY, PICTURE); copy a dense byte arry into a pic
		  GETPAR(ARRY, PICTR);	      copy full word array of pixels to pic
		  PUTPAR(PICTR, ARRY);	      copy pic to full word array of pixels

		  EDGEINIT(PICTURE,SIZE);	initialize edge operator
                  EDGE(X,Y,EDGERESULT);		apply edge operator

	NOTE: all picture and other arrays are zero origin in all dimensions
VIXHDR.SAI   for displaying grey scale and halftone pictures on data disc.
		an extension for the display routines in DDSUB.SAI[GRA,HPM]

	requires: PIXHDR.SAI[VIS],DDHDR.SAI[GRA],VIXFAI.REL[VIS],VIXSAI.REL[VIS]

	provides: VIDEO(X1,Y1,X2,Y2,PICTURE,BIT);
        	  VID(X1,Y1,X2,Y2,PICTURE,BIT);
			display PICTURE between X1,Y1,X2,Y2 in SCREEN
			co-ordinates. If BIT=-1 then a fast, low quality
			halftone, if -2 then a high quality halftone, if
			-3 then a buggy halftone. If positive then BIT
			represents a bit mask, which is anded with each
			pixel. If the result is nonzero, a bit is turned
			on in the corresponding part of the display.

		   VIDONE(PICTURE,BT,I(0),J(0));
			similar to VID but faster and simpler. Maps picture
			elements one to one to data disc points. Upper left
			corner of picture is placed I physical DD scanlines
			from the top of the picture, and indented J DD
			elements from the left. Complements the masked bit
			instead of setting it to one.

		   VIDFOR(PICTURE,BUF1,BUF2,BUF4,BUF8,I(0),J(0));
			Like VIDONE, but for 4 bit pictures and four DD buffers.
			Sets up all buffers at once, clearing displayed area
			and inverting bits for compatibility with the inverted
			gray code produced by TVRAW.

		   VIDFRT(PICTURE,BUF1,BUF2,BUF4,BUF8,I(0),J(0));
			Transposed VIDFOR, makes picture twice as wide on its side.

		   VIDFRX(PICTURE,BUF1,BUF2,BUF4,BUF8,I(0),J(0));
			Like VIDFOR, but makes a picture twice as wide and tall.
			One picture pixel → 4 DD pixels.

		   VID1(PICTURE,BUF1,I(0),J(0));
		   VID3(PICTURE,BUF1,BUF2,BUF4,I(0),J(0));
		   VID4(PICTURE,BUF1,BUF2,BUF4,BUF8,I(0),J(0));
		   VID5(PICTURE,BUF1,BUF2,BUF4,BUF8,BUF16,I(0),J(0));
			Like VIDFOR, for 1, 3, 4 and 5 bit pictures, but assumes
			normal gray code and produces a complemented display.

        SUCCESS  ← VIDXGP(PIC; I0,J0,PLEN);
			Send a picture to the XGP. Dumb thing to do except
			for one bit pictures. Wait if XGP busy.
        SUCCESS  ← VIDXG(PIC; I0,J0,PLEN);
			VIDXGP, but return with failure if XGP busy
        SUCCESS  ← VIDXGQ(PIC; I0,J0,PLEN);
			VIDXGP, but set up detached job to do XGPing if XGP busy
FNTHDR.SAI   for inserting XGP font characters into pictures.

	requires: FNTFAI.REL[VIS],FNTSAI.REL[VIS]

		   FNTSEL(FNTNUM,FILSPEC,FNTHEAD);
			define font number FNTNUM to be font FILSPEC.
			FNTHEAD is the first word of an array '204 words
			long which must be reserved for this font.

		   CHRDEP(FNTNUM,CHR,PIC,YLO,XLO,YCOMP,XCOMP);
			add character CHR to the picture PIC in font # FNTNUM
			starting at position YLO, XLO
			compressed by YCOMP in Y and XCOMP in X.

		   CHRPED(FNTNUM,CHR,PIC,YLO,XLO,YCOMP,XCOMP);
			add CHR to PIC, sideways, writing bottom to top.
			X and Y positions and compressions refer to text,
			not picture, reference system.

		   CHR3X2(FNTNUM,CHR,PIC,YLO,XLO);
			like CHRDEP, but compresses X by 3 and Y by 2, and
			goes faster

		   CHR6X4(FNTNUM,CHR,PIC,YLO,XLO);
			like CHRDEP, but compresses X by 6 and Y by 4, and
			goes faster

		   CHR3Y4(FNTNUM,CHR,PIC,YLO,XLO);
			like CHRPED, but compresses X by 3 and Y by 4, and
			goes faster

		   FCACHE(BUFFER,BUFSIZ);
			set up a buffer for caching letter descriptions.
			Doing this greatly speeds up CHRDEP. 5 or 10 K
			is a good buffer size.

		  Defines FNTHIG, position in FNTHEAD where height is stored,
                  and FNTBAS, where baseline is stored.
INTERNAL PICTURE ARRAY FORMAT

	WORD		CONTENTS
	
	0		PCLN   number of scanlines in the picture
	1		PCWD   words in the pixel portion of the picture
	2		PCBY   valid bytes in the picture
	3		PCBYA  bytes in the picture, including null
				bytes at end of each scanline

	4		LNWD   words per scanline
	5		LNBY   valid bytes per scanline
	6		LNBYA  bytes per scanline, including the nulls

	7		WDBY   bytes per word
	8		WDBI   bits in the valid portion of each word

	9		BYBI   bits per byte

	10		BMAX   2↑BYBI-1, the maximum value of a byte

	11		BPTAB  address of SECOND entry in byte pointer
				table 13+PCLN+address of array

	12 to 11+PCLN	LINTAB table containg the actual address of the first
				word of each scanline, in obvious order

	12+PCLN to 	table containing byte pointers to samples within
	 12+PCLN+LNBYA		lines, to be added to line address.
				The first entry, when ILDB'ed causes
				loading of the first byte in the line.

	13+PCLN+LNBYA to	the picture
	 12+PCLN+LNBYA+PCWD
PICTURE FILE FORMAT

Simplified hand-eye file format, as written by PIXSAI routines, for
a picture HIG samples high by WID samples wide by BIT bits/sample:

The first 200 (octal) word disk block of the file contains the following
7 words of data (the rest of the block is unused).

    WORD   CONTENTS
    ____   ________

    0      -1          This identifies the file as a Hand Eye picture file
    1      BIT         Number of bits/sample
    2      {WID/[36/BIT]} # of words/scanline. [] is FLOOR, {} is CEILING.
    3      1           (first
    4      HIG           and last scanline numbers)
    5      1	       (first
    6      WID            and last column numbers. Note the extra word)

The data begins on word 200 of the file, {WID/[36/BIT]} words per scanline,
left to right, top to bottom, for HIG scanlines. Each scanline begins
on a word boundary.